home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / gnu / progutil / stdwin.zoo / MANUAL < prev    next >
Text File  |  1989-10-17  |  48KB  |  1,193 lines
  1. STDWIN -- STANDARD WINDOWS
  2. --------------------------
  3. RATIONALE
  4. ---------
  5.  
  6. STDWIN was born by the desire to make using windows both easier and more
  7. portable for a certain class of applications.  To show why it should be
  8. easier than it currently is, consider for example the calls necessary to
  9. create a window on the Apple Macintosh:
  10.  
  11.     WindowPtr w;
  12.     Rect r;
  13.     
  14.     SetRect(&r, <desired window coordinates>);
  15.     w= NewWindow(
  16.         (Ptr)nil,        /* Optional storage */
  17.         &r,            /* Initial position/size */
  18.         documentProc,        /* Border frame type */
  19.         "Untitled",        /* Title */
  20.         true,            /* Immediately visible */
  21.         0L,            /* Reference constant */
  22.         (WindowPtr)-1        /* Behind no other window */
  23.     );
  24.  
  25. Since I'm doing this without documentation, I may have missed or
  26. reversed some parameters, which shows exactly what I want to illustrate:
  27. the call has too many options, most of which are of no interest to most
  28. application programmers.  Also, it forces the programmer to invent an
  29. initial position for the window, which is often a burden, since this
  30. means one also has to invent a scheme by which to offset the position
  31. for subsequent windows, to avoid creating windows that overlap exactly.
  32.  
  33. What this example doesn't show is the amount of code one has to write
  34. to provide the functionality that Mac users expect from even the
  35. simplest application: windows can be moved, resized, zoomed, closed,
  36. (de)activated, scrolled in two directions, and need to be explicitly
  37. redrawn when they pop up from below another window; none of this is done
  38. automatically by the window manager.  One needs hundreds of lines of
  39. code to provide all this functionality, and most of it has to be
  40. interspersed with application-dependent code (such as to actually draw a
  41. window's contents), which makes it harder to reuse the same code in the
  42. next program one writes.
  43.  
  44. There are other burdens to the application programmer who writes for the
  45. Macintosh, such as the large number of #include files that one must put
  46. in even the simplest programs, and the correspondingly large number of
  47. initialization calls one must make.
  48.  
  49.  
  50. Why using windows should be made more portable is clear if one considers
  51. what is necessary to port a program to a different machine like the
  52. Atari ST, the Commodore Amiga, or a Sun/3 running Suntools or X Windows
  53. (while all these use the same type of processor!).  Not only are the
  54. calls that interface to their window managers different, the semantics
  55. of windows are also subtly different.  Some systems remember a window's
  56. contents when it is covered by another window, so 'update events' are
  57. unheard of; some systems provide a standard interface to scroll bars or
  58. other tools; etc., etc.
  59.  
  60. This seriously limits productivity of application programmers: it can
  61. take many person-months to port a successful program to a new machine,
  62. even though one has used a high-level programming language such as C or
  63. Pascal.  While this effort may be economically justifyable for
  64. bestsellers like commercial spreadsheets or wordprocessors, there is a
  65. large class of applications where one can simply not afford these
  66. porting efforts, especially in the academic world, but also for many
  67. specialized applications which aim at a more limited market.
  68.  
  69.  
  70. The current design places an emphasis on full-function windows that give
  71. a scrollable 'view' on some kind of two-dimensional document, e.g. a
  72. program text editor or a graphics design program.  It provides some
  73. tools for simple modal input (e.g., to ask for a string or a file name)
  74. and gives a clean but powerful interface to the common types of pop-up
  75. or pull-down menus (with text items only).  What is clearly missing is a
  76. mechanism to put indicators, icons, controls, rulers, palettes, tool
  77. wells and other gadgets in the window border or on the 'desktop', and
  78. the ability to pop up a collection of gadgets in a dialog window as
  79. commonly seen on the Mac.  Suggestions for a general mechanism here
  80. which fits in STDWIN's philosophy are welcome.  (Are there any other
  81. systems besides the Macintosh and its derivatives like the ST or the
  82. Amiga that provide tools for controls and dialogs?)
  83.  
  84. I haven't placed too much emphasis on the design of the graphics
  85. primitives that must be used to draw the contents of a window.  There
  86. are simple routines to draw text strings in a single proportionally
  87. spaced font with a few stylistic variations, and to do simple line
  88. drawings and a few rasterop operations on rectangles.  I plan to extend
  89. the repertoire (and to implement defined functions) as the need arises;
  90. ideally, a standard such as GKS should be adopted, if we want fo
  91. accommodate applications with more drawing requirements.  The is nothing
  92. in the interface definition which precludes color drawing.
  93.  
  94. Although the documentation clearly describes the interface to a library
  95. of C functions, it shouldn't be to hard to translate the interface to
  96. other languages like FORTRAN or Modula.  Ideally, STDWIN should be
  97. defined as a set of 'abstract' functions for which language bindings can
  98. be provided, similarly to the definition of GKS.
  99.  
  100. --- Postscript ---
  101.  
  102. The general aim of STDWIN is to provide high-level features to
  103. applications which can be used with little effort.  Features provided
  104. must be implementable on top of a large number of window managers;
  105. therefore, no precise definitions of some semantical aspects of windows
  106. can be given, in order not to rule out certain implementations (example:
  107. there can be no mention of a 'stack' of windows, since we want to be
  108. compatible with tiling window managers).  This may impair the freedom of
  109. applications, but will enforce a useful standardization of applications
  110. running on a particular system.
  111.  
  112. In many cases STDWIN provides a way to change the default behaviour
  113. if this is considered useful for the application; sometimes such
  114. default-changing routines have an optional or approximate effect,
  115. depending on whether they can be implemented on a particular system.
  116. For best effect this may require some system-dependent tuning when an
  117. application is ported.
  118.  
  119. DEFINITIONS OF TERMS
  120. --------------------
  121.  
  122. Here are short definitions of many of the terms used in the descriptions
  123. below.  Not all of these definitions are as precise as they could or
  124. should be.  Suggestions for improvement (also about the order of
  125. presentation) are welcome.
  126.  
  127. Window
  128.     A (usually) rectangular area on the screen which contains a view
  129.     on a document.  A window is linked to one particular document;
  130.     it has a title and 'borders', which usually contain scroll bars,
  131.     a grow box and possibly other controls and indicators.  The end
  132.     user may usually change a window's position and size, as well as
  133.     the part of the document onto which the window gives a view.
  134.  
  135. Document
  136.     The (abstract) data structure onto which a window gives a view.
  137.     A document is a rectangular portion of the plane, with maximum h
  138.     and v coordinates which can be set by the application, but it is
  139.     NOT a bitmap: a document may be much larger than the largest
  140.     bitmap that fits in main memory, and it is defined by a 'draw
  141.     procedure'.
  142.  
  143. Window tag
  144.     A small (16-bit) integer used to distinguish windows.  It is set
  145.     by the application.
  146.  
  147. Draw procedure
  148.     The function that defines a document.  When called with the
  149.     coordinates of a rectangle, it should draw (at least) that part
  150.     of the document that lies within this rectangle, using the
  151.     drawing primitives provided by STDWIN, e.g. wdrawline()
  152.     and wdrawtext().
  153.  
  154. Document coordinates
  155.     All coordinates passed to and from STDWIN functions use a
  156.     coordinate system called 'document coordinates'.  These are
  157.     derived through translation from window or screen coordinates:
  158.     the origin of the document is called (0, 0), independent of its
  159.     position on the screen or in the window.  This origin is
  160.     positioned in the UPPER left corner of the document, with the
  161.     positive horizontal (h) axis pointing right and the positive
  162.     vertical (v) axis pointing DOWN.  Document coordinates are
  163.     specified as integers.
  164.  
  165. Pixels
  166.     Are the units of measurement of document (and other)
  167.     coordinates.  The size of a pixel is system-dependent; on most
  168.     screens it is equal to a screen pixel, but on alphanumeric
  169.     displays it equals a character.  There is no guara